The Template Results panel displays variables that were generated by running a Binary Template on a file (see Introduction to Templates and Scripts) and this panel is shown by default attached to the bottom of the Hex Editor Window (see Using the Hex Editor). To hide the Template Results panel click on the 'x' icon to the right of the Template Results title or click the 'View > Template Results' menu option when a file is opened. If the Template Results panel is hidden, it can be shown by clicking the 'View > Template Results' menu option or by clicking the button underneath the vertical scroll bar and dragging upwards (see the diagram below). The Template Results can be attached to the right side of the Hex Editor Window by right-clicking on the Template Results and choosing the Template Results Position menu option. Alternately, the Template variables can be viewed by clicking on the Variables Tab of the Inspector. To the right of the Template Results title is the name of the Template that has been run and the icon. Clicking the icon causes the Template to be run again. Additional information is shown in the header when the Template is run from an offset as described in the Running Templates at an Offset help topic. To see an example of a Template open any ZIP, BMP, or WAV file on your computer and a Binary Template will automatically be run and the results displayed.
The Template Results panel displays 7 different columns: The Name column lists the name of the variable including any array indices, and can be set to show the data type as well. The Value column displays the value of the current variable as read from the file. The Start column lists the starting address of the variable and the Size column lists the size in bytes of the data. The data type of the variable is shown in the Type column. The Color column shows the background color in a box and if a foreground (text) color is assigned then the word Text is drawn in the foreground color. The Comment column displays a string that can be set after a variable is declared using the syntax '<comment="<string>">' or '<comment=<function_name>>' (see Declaring Template Variables). To clear the Template Results, right-click on the panel or the Variables tab of the Inspector and select the 'Clear' menu option.
Opening and Closing Nodes
All variables are displayed in a hierarchal list. If a variable in the list has a right arrow or '+' beside it that variable is either a structure or array. Clicking the arrow or plus or double-clicking the variable will show all members within that variable. If a variable has a down arrow or '-' beside it click the icon or double-click the variable to hide all members. The Left and Right arrow keys can also be used to open or close nodes as discussed in the next section. When a variable is selected, the bytes that correspond to that variable are selected in the file.
To open the entire sub-tree below a variable, right-click on a variable with the mouse and select the Expand All Children of Node menu option, or right-click on a variable and select Expand All Nodes to open all children of all nodes in the tree (note that the syntax '<open=suppress>' can be used after a variable to prevent it from being opened in an Expand All operation).
Shortcut Keys
When the Template Results is selected the following shortcut keys can be used:
- Down - Selects the next variable in the list.
- Up - Selects the previous variable in the list.
- Right - Opens the current variable.
- Left - Closes the current variable. If the variable cannot be closed then the parent of the current variable is selected instead.
- Enter - Edits the current variable. If the current variable cannot be edited but is a parent node, the the open status of the node is toggled.
The Left and Right keys may change if a different Select by is chosen as discussed in the Using Tables help topic.
Editing Values
To edit the value of a variable, double-click the text in the Value column or press the Enter key. Modify the value and press Enter to commit the change or Esc to cancel. Editing is performed similar to the Inspector and note that date formats can be controlled using the Inspector Options dialog. If no value is displayed in the Value column, this means that the variable cannot be edited.
Right-Click Menu
Many of the menu options on the right-click menu are similar to the Inspector. See the Inspector help topic for information on the 'Copy', 'Copy Row', 'Copy Column', 'Copy Table', and 'Export CSV' options. Use the 'Export XML' menu option to export data from the Template Results in XML format (note that XML files are written in UTF-8 format). Other options on the right-click menu are discussed below.
Display Formats
The display format for the different columns can be changed by right-clicking on the window and selecting 'Column Display Format' from the menu. This menu can also be accessed by right-clicking on the header of the table. For the Value Column, if the 'Default' option is chosen then the display format is determined when running the Template from the functions DisplayFormatHex, DisplayFormatDecimal, DisplayFormatBinary, or DisplayFormatOctal, or by using '<format=hex|decimal|octal|binary>'. For Name Column the format can be set to 'Type and Name' to show both the variable type and name, or set to 'Name' to just display the variable name. For Start Column the display can be set to either 'Hex' or 'Decimal' and the Start Addresses can be set to 'Global', 'Local', or 'From Offset'. In 'Global' mode, the addresses are displayed as regular addresses from the beginning of the file, in 'Local' mode addresses are displayed as the offset from its parent variable, and in 'From Offset' mode addresses are displayed as offset from a Template Offset as defined in the Run Template dialog. For Type Column the column can be hidden by unchecking the 'Show Column' option.
Struct Outlining and Hints
Placing the mouse cursor over bytes in the Hex Editor that correspond to a variable in a Template will cause those bytes to become highlighted as shown above. Keeping the mouse still for a second will also show a hint popup with more information about the variable. If a variable is a member of a struct then the whole struct will be shown with an outline and this is called struct outlining. Currently only one struct is shown as outlined. The variable highlighting, hint display, and struct outlining can all be turned off using the Hex Editor Options dialog. The current struct is also highlighted in the Mini Map.
Goto Definition
To locate the line of code in a Template that created a variable, right-click on the variable in the Template Results and select Goto Definition. This operation will show the source Binary Template and position the cursor at the line where the variable was defined. If the variable was created inside an include file, the include file will be loaded instead. If the variable is not one of the base data types; for example int, short, float, etc.; then another option will appear on the right-click menu called Goto Type Definition. Clicking this option will open the source Binary Template and position the cursor at the line where the type was defined. If a variable is a struct then the cursor will be positioned where the members of the struct are defined. The source code below demonstrates the different between Goto Definition and Goto Type Definition for structs:
typedef struct {
char signature[4];
ushort version;
ushort flags;
} HEADER; // this is where the variable type is defined
HEADER fileHeader; // this is where the variable is defined
Goto Type Definition also works with enums and other typedefs. If the source code was modified since the Template was run, a warning is displayed in the status bar and the correct line in the file may not be located.
Local Variables
By default, the Template Results does not display any local variables (see Declaring Template Variables for more information on local variables). To enable the display of local variables right-click on the panel and select the Show Local Variables menu option from the menu.
Goto Address or Sector
If the value for a variable displayed in the Value column is a hex or decimal number, right-click on the variable and select 'Goto > Goto Address <number>' or 'Goto > Goto Sector <number>' from the popup menu to jump to that byte address or sector within the file. For example, if a variable has the value '10324', right-click on the variable and choose 'Go to > Go to Address 10324' to jump to address 10324.
Locating Variables
To locate a variable in the list that corresponds to a byte position in the file, position the cursor over a byte in the Hex Editor Window and then use the 'Find > Jump to Template Variable' menu option to try to locate the variable (see Find Menu). Variables can also be located by string value using the Find Bar. To locate the source code that corresponds to a variable see Goto Definition.
|